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RECOMMENDATIONS FOR FACILITY DOCUMENTATION 


INFORMATION REQUIRED FOR EACH SERVICE AVAILABLE TO THE NETWORK 


There are two classes of information which a site needs to provide 
for each service or process it makes available over the Network: 


i) information required by system programmers in order to 
establish a connection to the facility 


ii) information required by a user to gain access to and use the 
facility 


The above two basic kinds of information which need to be in each 
facility description will comprise a "functional document" (see RFC 
115, NIC (5822,) for a description of functional documents and 
recommended procedures for updating them). 


The information required by user site system programmers may be a 
detailed document or a reference to a document containing a protocol 
common to several facilities or some combination of the above. All 
information required such as connection socket numbers, message 
formats, and character set information must be included. Two 
examples of system programmer type information are RFC 74, NIC 
(5417,) and RFC 105, NIC (5775,) prepared by James White of UCSB. 


The information required by user site users is of three types: 


a) information unique to Network users of the facility 


b) information in common between Network users and server site 
users of the facility 


c) information unique to particular Network user site. 
The information of type c) would be prepared by the user site from 
the information provided by the server site. An example might be 


keying conventions required in order to send certain codes to the 
server site. 
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Future documentation will probably be written with information types 
a) and b) above integrated in one document, but initially server 
sites will probably have user manuals or documentation for their 
local users and will need to write a short document giving any 
additional information required for Network users. This information 
will vary, but might include a different login or control card 
sequence, varying echo or syntax for user sites operating with 
character at a time, line at a time, server site or user site echoing 
and so forth. Some features available to server site users may not 
be available to Network user site users or certain features may 
behave differently. 


In addition to the above types of information, there should be 
instructions to the user on how to obtain help or answers to 
questions about using the facility. 


Information about how to obtain administrative access (charge 
numbers, etc.) to a site should be contained in the document, ARPA 
Network Current Guides to Network Facilities, NIC (5148,). This 
information is being collected by BBN. This document will in turn 
contain references to the functional documents containing detailed 
descriptions of available Network facilities and how to use them. 


Even if there are no special conventions or information unique to a 
Network user as opposed to a server site user, this fact should be 
explicitly stated in order to avoid confusion or uncertainty. 


NETWORK INFORMATION CENTER POLICY ON DISTRIBUTION AND UPDATING OF 
DOCUMENTATION 


The Network Information Center will distribute and maintain one copy 
of each functional document describing a facility in each Network 
Station NIC Collection. For this purpose we would appreciate it if 
100 copies of each manual and set of manual updates, when they occur, 
could be sent to the NIC. Users at sites desiring their own copies 
of user documentation can obtain them either directly from the server 
site or by copying the master in their local NIC Collection. In 
order that users may know where to obtain additional copies of the 
documentation, an address and a price, if any, should be included in 
the information about each facility. 
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